home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 February / EnigmA AMIGA RUN 15 (1997)(G.R. Edizioni)(IT)[!][issue 1997-02][PLANET CD V].iso / enigma / earcd / utility / utilfile / rw2ent15.lha / Raw2Ent.doc < prev    next >
Text File  |  1996-11-10  |  14KB  |  445 lines
  1. Project: Raw2Ent
  2. ARexx  : Raw2Ent.rexx
  3. Version: 1.4.1 (14.07.96)
  4. Program: Raw2Ent
  5. Version: 1.5 (10.11.96)
  6. Author : Tamio Patrick Honma
  7.  
  8. Files  : CWISENV
  9.          Raw2Ent
  10.          Raw2Ent.doc
  11.          Raw2Ent.rexx
  12.          Raw2Ent.rexx.old
  13.  
  14.  
  15.  
  16. CONTENTS:
  17.  
  18. 1. INTRODUCTION
  19. 1.1. REQUIREMENTS
  20.  
  21. 2. USAGE
  22. 2.1. Raw2Ent VER: 1.5 (10.11.96)
  23. 2.2. Raw2Ent.rexx VER: 1.4.1 (14.07.96)
  24. 2.3. CWISENV
  25. 2.4. ARGUMENT-PRIORITY
  26.  
  27. 3. LIMITATIONS
  28.  
  29. 4. INSTALLATION
  30.  
  31. 5. EXAMPLES
  32.  
  33. 6. BYE!
  34.  
  35. 7. LAST COMMENT
  36.  
  37. 8. BUG REPORTS
  38.  
  39. 9. HISTORY
  40.  
  41.  
  42.  
  43.  
  44. 1. INTRODUCTION
  45.  
  46. Raw2Ent   converts   raw   8-Bit-ASCII-Text   into   7-Bit-ASCII-Text   with
  47. entity-codes  and  reverse.   The  ASCII-Format is a standardized format for
  48. information  interchange,  but it is only standardized seven-bit-wide, which
  49. means  that  128 codes are defined.  One Byte consists of eight bits and can
  50. represent  256  different  bit  combinations.   Therefore  the  last 128 bit
  51. combinations  are defined for free use by any operation-system.  The problem
  52. is that accent-characters and other special characters are not standardized,
  53. because  they  are defined in (guess where?!  ;) ) the free part of ASCII by
  54. the operation system developers.
  55.  
  56. The  goal of the Wold Wide Web developers was that it could be used on every
  57. important   operation   system.   So  it  was  clear  that  the  ASCII-Based
  58. HTML-Source-Code   had  to  use  the  standardized  seven-bit  area  of  the
  59. ASCII-Code.  To represent accent-characters or other special characters in a
  60. seven-bit-code,  it  was  neccesary  to  invent something.  And this was the
  61. entity-code  -  a  kind  of  escape-code.   An  entity-code  consists  of an
  62. introducing  "&"  and  a  ";"  at  the  end.   Between  these  symbols  is a
  63. character-name the browser can interpret.  It is a very hard and stupid work
  64. to convert the ASCII-Text by hand.  So just use Raw2Ent!
  65.  
  66. Raw2Ent  produces  real 7-Bit-ASCII-Code.  All printable Amiga-characters in
  67. the  8-bit-area  will be converted into entity-codes, without any exception.
  68. The  use  of names instead of code-numbers will make the entity-codes easier
  69. to be read by humans.
  70.  
  71.  
  72. 1.1. REQUIREMENTS
  73.  
  74. - AmigaOS 2.0 or greater
  75. - optional: ARexx
  76.  
  77.  
  78.  
  79. 2. USAGE
  80.  
  81. Raw2Ent  consists  of  three parts:  one assembler-program, one ARexx-Script
  82. and one Batch-File.
  83.  
  84. If   you   just   want   to   convert   a  text  once,  you  just  need  the
  85. assembler-program.   If  you  want  to  convert  one text more than one time
  86. because  you work on a project, like a web-page with actual information, the
  87. ARexx-Script may be useful.
  88.  
  89.  
  90.  
  91. 2.1. Raw2Ent VER: 1.5 (10.11.96)
  92.  
  93. arguments:
  94.  
  95.   FROM/A            - The source-file (eight bit wide)
  96.   TO/A              - The destination-file (with entity-codes)
  97.                       [path without filename is not accepted]
  98.   TAG/S             - activates the TAG-Mode
  99.   HTML/S            - activates the HTML-Mode
  100.   ENT/S             - default mode
  101.   UML=NOENT/S       - removes high-bit characters by characters or words
  102.   CODE/S            - converts all entity-codes by code-number
  103.                       (except the four special entities)
  104.   TOTALCODE/S       - converts ALL characters by entity-code-numbers
  105.   SMART/S           - activates the smart-mode
  106.   INVERSE=ENT2RAW/S - inverses the function of Raw2Ent to Ent2Raw
  107.  
  108.  
  109. modes:
  110.  
  111.  
  112. >TAG-Mode<
  113.  
  114. will  not  convert  the  four  characters:   &  <  > ".  This is usefull for
  115. ASCII-Text  which  already  contains  entity-codes  or  HTML-TAGS, which are
  116. introduced  and  ended  by  "<"  and  ">" and which can contain quotes.  The
  117. "&"-character  usually introduces the entity-codes.  If you use the TAG-Mode
  118. the entity-codes in the source-file will not be converted a second time in a
  119. wrong  way,  but  untouched special-characters will be converted.  Therefore
  120. you should use this mode, whenever you convert a text a second time.
  121.  
  122.  
  123. >HTML-Mode<
  124.  
  125. will  just  copy  the  source-file to the destination-file.  This feature is
  126. implemented  to  make the program be easier used in script-files.  (see i.e.
  127. Raw2Ent.rexx)
  128.  
  129.  
  130. >ENT-Mode<
  131.  
  132. is the default mode and converts every known character into its entity-code.
  133.  
  134.  
  135. >NOENT-Mode< or >UML-Mode<
  136.  
  137. is  a  mode,  which  replaces  each  high-bit character by characters in the
  138. low-bit  area  without  using  character-entity-codes.   I.e.:   "ü" will be
  139. converted  to  "ue"  and  "£"  will  be converted to "pound" and "©" will be
  140. converted  to  "(C)"  and  so on.  It is recommended to use this argument in
  141. accompany  with  the  "TAG"-argument.   Optionally  you can use >UML< (like:
  142. Umlaute),  which  is  a  synomnym  to  >NOENT<.   [This mode was inspired by
  143. Andreas Bais]
  144.  
  145.  
  146. >CODE-Mode<
  147.  
  148. will   convert  all  entity-codes  not  by  the  entity-names,  but  by  the
  149. entity-code-numbers.   This may be usefull, if a browser doesn't support all
  150. entity-names, but the numbers.  Note:  On the one hand code-numbers are hard
  151. to  be  read  by  humans,  but on the other hand the destination-file may be
  152. shorter.  [The shortest files may be converted in the "TAG NOENT"-Mode.]
  153.  
  154.  
  155. >TOTALCODE-Mode< or >TOTCODE-Mode<
  156.  
  157. will  convert EVERY character by its code-number.  The only use of this mode
  158. is to make it hard for humans to read the text-file.  This text will only be
  159. displayed  readable  by  a  HTML-Browser.  This mode will surely produce the
  160. largest destination-files!
  161.  
  162.  
  163. >SMART-Mode<
  164.  
  165. is  a  combination  of  the  >ENT<-Mode  and the >TAG<-Mode.  HTML-Files for
  166. example   will   be   converted   without   destruction   of  HTML-Tags  and
  167. character-entity-codes  -  like  the >TAG<-Mode.  The difference is that the
  168. characters:   <  >  &  "  will  be  converted, if Raw2Ent "thinks" that this
  169. characters are no elements of the character-entity-codes or HTML-Tags.  This
  170. works the best, if the HTML-File contains "good" code.  I cannot guarantee a
  171. correct  interpreatation  by  Raw2Ent,  but  I  think  it  works with 95% of
  172. HTML-Files without mistakes.
  173.  
  174.  
  175. >INVERSE-Mode< or >ENT2RAW-Mode<
  176.  
  177. converts  all character-entity-codes (names or numbers) into the Amiga-ASCII
  178. -  the  Latin-1  standard.  So you can use Raw2Ent as a Ent2Raw.  If you set
  179. the  >TAG<-Mode,  this  Mode  will not touch the codes:  > < & and
  180. ".
  181.  
  182.  
  183.  
  184. return-codes:
  185.  
  186. $RC=0  (OK)    -> everything's fine!
  187. $RC=5  (WARN)  -> wrong usage
  188. $RC=10 (ERROR) -> error (memory)
  189. $RC=20 (FAIL)  -> failure (input/output)
  190.  
  191.  
  192. 2.2. Raw2Ent.rexx VER: 1.4.1 (14.07.96)
  193.  
  194. arguments:
  195.  
  196.   FROM/A            - The source-file (eight bit wide)
  197.   TO/A              - The destination-file (with entity-codes)
  198.                       [path without filename is not accepted]
  199.   TAG/S             - activates the TAG-Mode
  200.   HTML/S            - activates the HTML-Mode
  201.   ENT/S             - default mode
  202.  
  203.  
  204. modes:
  205.  
  206.   see Raw2Ent-Usage (2.1.)
  207.  
  208.  
  209. Raw2Ent.rexx manages:
  210.  
  211.   - destination-path without filename
  212.   - suffix-handling (destinationfile has the suffix ".ent")
  213.   - progress-display
  214.   - enviroment-variables for automation without mistakes
  215.  
  216.  
  217.  
  218. 2.3. CWISENV
  219.  
  220. Use  CWISENV  to  set  the  enviroment-variables for a specific file, if you
  221. don't want to use the Raw2Ent.rexx-arguments - i.e. in batch-files.
  222.  
  223. arguments:
  224.  
  225. FILENAME/A  -  is  the filename of the input-file for Raw2Ent.  NOTE:  Don't
  226.                use  pathnames!  You must use the "cd"-command with the
  227.                pathname, where your textfile (input) can be found.
  228.  
  229. MODE/A      -  selects the Mode. You can choose: ENT, TAG, HTML
  230.  
  231. modes:
  232.  
  233.   see Raw2Ent-Usage (2.1.)
  234.  
  235.  
  236.  
  237. 2.4. ARGUMENT-PRIORITY
  238.  
  239. highest priority  FROM/A      -  Must be used!
  240.        ^          TO/A        -  Must be used!
  241.        |
  242.        |          INVERSE/S   -  disables ALL other switches except "TAG"
  243.        |          HTML/S      -  disables ALL the rest of the switches
  244.        |          TOTALCODE/S -  disables ALL the rest of the switches
  245.        |          CODE/S      -  disables the switches: "NOENT" and "ENT"
  246.        |          NOENT/S     -  disables the switches: "ENT" and "SMART"
  247.        |          TAG/S       -  disables the switches: "ENT" and "SMART"
  248.        v          SMART/S     -  disables the switch  : "ENT"
  249. lowest priority   ENT/S       -  doesn't affect other switches
  250.  
  251.  
  252.  
  253. 3. LIMITATIONS
  254.  
  255.   - A text can only be converted in one part. No markup possible.
  256.   - The enviroment-variables have no information about paths.
  257.     So i.e. all "index.html"-files have the same variable.
  258.     The variables are ignored, if you set the "TAG"- or "HTML"- or "ENT"-Switch
  259.     on your own. Please note that only the ARexx-Script supports variables -
  260.     NOT the assembler-program!
  261.   - No convertion-progress-display implemented. If you want to have this, you
  262.     can use the old ARexx-Script Raw2Ent.rexx v1.3.
  263.   - The old ARexx-Script [1.3] is not compatible to the assembler program.
  264.   - Raw2Ent cannot be stopped by the break signals.
  265.   - Raw2Ent just supports the Amiga-8-Bit-ASCII [ISO-8859-1], but this is okay
  266.     because there are many ways to convert texts from PC, Mac, Unix and other
  267.     systems:
  268.     - Use the CrossDOS-Commodity. (This is the best way - because every
  269.       AmigaOS 2.1+ User has this program in the Tools/Commodities-directory!)
  270.     - There are many converters in AmiNet or other Freeware-Sources. I.e.:
  271.       - "CharConv" by Johan Billing [v1.6 from 1994]
  272.   - If you search for a good HTML to TXT converter, then try this one:
  273.     - "HTTX" by Gabriele Favrin [v1.0 from 1996]
  274.  
  275.  
  276. 4. INSTALLATION
  277.  
  278. 4.1. Copy "Raw2Ent" and "Raw2Ent.rexx" into the same directory.
  279.  
  280. 4.2. Change the path-name in the "Raw2Ent.rexx"-Script.
  281.  
  282. 4.3. makedir ENVARC:cwis/
  283.  
  284.  
  285.  
  286. 5. EXAMPLES
  287.  
  288.  
  289. 5.1. "Raw2Ent Text.html Text.ent TAG"
  290.  
  291. Converts  the  file  "Text.html"  into  the  file "Text.ent" by entity-codes
  292. without destruction of HTML-Tags and already converted Entity-Codes.
  293.  
  294.  
  295.  
  296. 5.2. "Raw2Ent Text Text.ent" or
  297.      "Raw2Ent Text Text.ent ENT"
  298.  
  299. Converts the file "Text" into "Text.ent" without having regard for HTML-Tags
  300. or already converted Entity-Codes.
  301.  
  302.  
  303.  
  304. 5.3. "Raw2Ent Text.html Text.ent HTML"
  305.  
  306. Just copies the file "Text.html" to "Text.ent".
  307.  
  308.  
  309.  
  310. 5.4. "Raw2Ent Text.html Text.ent TAG CODE"
  311.  
  312. Same  as  example  5.1. but  all  character-entity-codes  are represented by
  313. code-numbers and no code-names.
  314.  
  315.  
  316.  
  317. 5.5. "Raw2Ent Text Text.ent CODE"
  318.  
  319. Same  as  example  5.2. but  all  character-entity-codes  are represented by
  320. code-numbers,  except  the  four  characters:   <  >  "  ?,  which are still
  321. represented by their character-entity-names.
  322.  
  323.  
  324.  
  325. 5.6. "Raw2Ent Text Text.uml TAG NOENT" or
  326.      "Raw2Ent Text Text.uml TAG UML"
  327.  
  328. This  will  convert  raw  text  into  seven-bit-wide-text without the use of
  329. character-entity-codes.   Raw2Ent  will  convert  the  text with alternative
  330. characters or words or shortcuts.  The destination-file in this example will
  331. contain  not  a  single  character-entity-code,  because  of  the use of the
  332. >TAG<-argument.
  333.  
  334.  
  335. 5.7. "Raw2Ent Text Text.code TOTALCODE"
  336.  
  337. The  file  "Text.code"  will  contain just code-number-entities, without any
  338. exception.  The destination file will be very large! Note: The TAG-Mode will
  339. be ignored, if you use this mode. Therefore you will not be able to use this
  340. mode for HTML-Files, but you can only read this file with a HTML-Browser.
  341.  
  342.  
  343. 5.8. "Raw2Ent Text.ent Text INVERSE" or
  344.      "Raw2Ent Text.ent Text ENT2RAW"
  345.  
  346. This will convert the file "Text.ent" to the Amiga-ASCII-File "Text".
  347.  
  348.  
  349. 5.9. "Raw2Ent Text.ent Text TAG INVERSE" or
  350.      "Raw2Ent Text.ent Text TAG ENT2RAW"
  351.  
  352. This  is  the  same  as 5.8..  The only difference is, that the codes:  >
  353. < & and "e; will not be converted.
  354.  
  355.  
  356.  
  357. 6. BYE!
  358.  
  359. ----------------------------------------------------------------------------
  360.        THE AUTHOR IS NOT RESPONSIBLE FOR ANY LOSS OF DATA OR DAMAGE!
  361.  
  362.                 USE THIS FREEWARE-PROGRAM ON YOUR OWN RISK.
  363. ----------------------------------------------------------------------------
  364.  
  365. Send comments to:
  366.  
  367. Tamio Patrick Honma
  368.  
  369. eMail: honma@thepentagon.com
  370.   WWW: http://www.netforward.com/thepentagon/?honma
  371.  
  372.  
  373. P.S. This program was made for the CWIS-Script-System on Amiga and PC.
  374.      The CWIS of the Heinrich-Heine-Universität Düsseldorf can be found here:
  375.  
  376.      http://www.phil-fak.uni-duesseldorf.de/cwis/
  377.  
  378.  
  379.  
  380.  
  381. 7. LAST COMMENT:
  382.  
  383. Hey!?    What   do  you  want!?   I'm  just  a  sociology-,  education-  and
  384. information-science-student and no programmer-student!
  385.  
  386. Just send me your bug-reports, ... ;)
  387.  
  388.  
  389.  
  390. ---> Raw2Ent-Assembler-Program <---
  391.  
  392. 8. BUG REPORTS:
  393.  
  394. Reported by        Bug                                          fixed Version
  395.  
  396. Joakim Andersson   Entity-Codes Å and å missing     1.0.1 (04.09.96)
  397.  
  398. Tamio Honma        Last Byte in destination-file has been       1.1 (05.09.96)
  399.                    deleted
  400.  
  401. Tamio Honma        Version-String missed one space-char         1.1.1 (06.09.96)
  402.  
  403. Marcus Beranek     Entity-Codes to ÿ,ï,Ï,æ,Æ,ø,Ø,ë,Ë missing    1.1.3 (06.09.96)
  404.  
  405. Tamio Honma        Mistake in circumflex-accents                1.1.4 (08.09.96)
  406.  
  407.  
  408. 9. HISTORY:
  409.  
  410. Version  Feature                                                Date
  411.  
  412. 1.0      first release                                          13.07.06 (*)
  413.  
  414. 1.1      Improved the speed approx 20 (!!!) times!              05.09.96
  415.          Version-String added
  416.  
  417. 1.1.2    Optimised code (speed increased)                       06.09.96
  418.          Return-Codes added (see paragraph 2.1 for return-codes)
  419.  
  420. 1.1.3    HTML-Tags to °,¹,²,³ added (faked)                     06.09.96
  421.  
  422. 1.1.4    All Entity-Codes available on Amiga-Charset included!  08.09.96 (*)14
  423.          Entity-Codes refering to the HTML 3.2 standard
  424.          All available names included
  425.          Codes without names represented by code-number
  426.          faking HTML-Tags removed
  427.  
  428. 1.1.5    Just changed a code-number by entity-name "§"     14.10.96
  429.  
  430. 1.1.6    changed all code-numbers to entity-names (completely!) 30.10.96
  431.  
  432. 1.2      added CODE-Mode                                        01.11.96 (*)
  433.  
  434. 1.3      added NOENT-Mode and TOTALCODE-Mode                    03.11.96 (*)
  435.          Version-String will be displayed in the usage-text
  436.  
  437. 1.4      added SMART-Mode                                    06-07.11.96 (*)
  438.  
  439. 1.5      added INVERSE-Mode for names and codes (Ent2Raw)    07-10.11.96 (*)
  440.          added HELP-Text
  441.  
  442.  
  443. (*) = released in Aminet
  444.       number represents the number of the Aminet CD-ROM
  445.